home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / workbench / tools / czesc_1 / executive_v1.00 / sysinfo.lzx / sysinfo.doc < prev   
Text File  |  1990-07-25  |  21KB  |  666 lines
  1. TABLE OF CONTENTS
  2.  
  3. sysinfo.library/--background--
  4. sysinfo.library/AddNotify
  5. sysinfo.library/FreeSysinfo
  6. sysinfo.library/GetCpuUsage
  7. sysinfo.library/GetLoadAverage
  8. sysinfo.library/GetNice
  9. sysinfo.library/GetPgrp
  10. sysinfo.library/GetPid
  11. sysinfo.library/GetPpid
  12. sysinfo.library/GetTaskCpuUsage
  13. sysinfo.library/InitSysinfo
  14. sysinfo.library/RemoveNotify
  15. sysinfo.library/SetNice
  16. sysinfo.library/--background--             sysinfo.library/--background--
  17.  
  18.   PURPOSE
  19.  
  20.     Sysinfo.library was developed to bring together all the different
  21.     utility programs that add some new features to Amiga task
  22.     handling, like CPU usage calculation. Sysinfo.library was first
  23.     developed for Executive, but it's possible to rewrite it to
  24.     support other similar programs. It's not necessary to support
  25.     all sysinfo.library functions in all implementations.
  26.  
  27.   OVERVIEW
  28.  
  29.     Currently supported features
  30.  
  31.     * CPU usage
  32.  
  33.       Sysinfo.library provides several CPU usage indicators, e.g.
  34.       total used CPU time, CPU time used during last second,
  35.       recently used CPU time. Executive will also provide context
  36.       switch counters.
  37.  
  38.     * load averages
  39.  
  40.       Load average is the number of tasks ready or running over various
  41.       periods of time, usually 1, 5 and 15 minutes. A load average 1.0
  42.       means that there has been exactly one task running.
  43.  
  44.     * PID, PPID and PGRP
  45.  
  46.       PID is a process identifier. This is a unique number assigned for
  47.       each task in the system.
  48.  
  49.       PPID is a parent process identifier. It's the PID of the process
  50.       that has created the current process.
  51.  
  52.       PGRP is a process group. Process groups can't be implemented on
  53.       Amiga at the moment, because it's impossible to distinguish
  54.       if a task is a child-task or a totally separate task. In Executive
  55.       process groups mean processes created by a specific task. The
  56.       PGRP number is the PID of the parent task. By referring to a specific
  57.       process group, you refer to all tasks created by the parent task.
  58.  
  59.     * nice-values
  60.  
  61.       Nice-values similar to Amiga priorities, they are used by the
  62.       scheduler when calculating priorities for different tasks.
  63.  
  64.   NOTES
  65.  
  66.     If some function can't be implemented, a valid error-value
  67.     should still be returned.
  68.  
  69.     A `server' in this document means the program calculating all
  70.     this information. Sysinfo.library is a standard interface to
  71.     different servers.
  72.  
  73.   AUTHOR
  74.  
  75.     Petri Nordlund <petrin@mits.mdata.fi> or <petrin@sik.ppoy.fi>
  76.  
  77.   HISTORY
  78.  
  79.     V1.00  First release
  80.  
  81.   FUTURE
  82.  
  83.     Here are some functions which could be included in sysinfo.library:
  84.  
  85.     acct
  86.     getegid
  87.     geteuid
  88.     getgid
  89.     getgroups
  90.     getlogin
  91.     getrlimit
  92.     getrusage
  93.     getuid
  94.     setegid
  95.     seteuid
  96.     setgid
  97.     setgroups
  98.     setlogin
  99.     setpgrp
  100.     setpgid
  101.     setrlimit
  102.     setsid
  103.     setuid
  104. sysinfo.library/AddNotify                  sysinfo.library/AddNotify
  105.  
  106.   NAME
  107.     AddNotify - Add a notification request
  108.  
  109.   SYNOPSIS
  110.     sysinfo_notify = AddNotify(sysinfo,use_messages,safety_limit);
  111.     D0                         A0      D0       D1
  112.  
  113.     struct sysinfo_notify *AddNotify(struct sysinfo *, BOOL, ULONG);
  114.  
  115.   FUNCTION
  116.     Ask the server to notify us after it has updated it's information.
  117.     After the notification, new load average, CPU usage and other
  118.     information may be requested and they'll be up-to-date. Notification
  119.     is useful if your application updates it's display frequently.
  120.     You don't end up updating just before the server will calculate
  121.     new information. The notification will keep your application in sync
  122.     with the server.
  123.  
  124.     There are two ways to notify your task, by signals or messages.
  125.     Signals are very fast, but they don't queue. The safety_limit
  126.     variable can be used with messages, it's the maximum number of
  127.     notification messages that will be sent to you before you reply
  128.     to them. A good value here is about 10 - 20.
  129.     
  130.     This function returns a sysinfo_notify structure, which you
  131.     must not modify. If you use messages for notification, it has
  132.     a pointer to a port where the messages will arrive. Just reply
  133.     to the messages you get. There may be some internal information
  134.     in these messages that the server will use so don't modify them.
  135.     If you have ask for signals to be used for notification, there
  136.     will be a signal number in the structure. Just Wait() for that
  137.     signal.
  138.  
  139.     Before requesting notification, make sure that it's implemented.
  140.     The sysinfo->notify_sig_implemented is TRUE if you can use
  141.     signals and the sysinfo->notify_msg_implemented is TRUE if
  142.     notification with messages is available.
  143.  
  144.     A notification happens once every second.
  145.  
  146.   INPUTS
  147.     sysinfo - sysinfo structure returned by InitSysinfo()
  148.     use_messages - TRUE to use messages, FALSE to use signals
  149.     safety_limit - maximum number of messages sent to you
  150.  
  151.   RESULT
  152.     sysinfo_notify - a structure defined in <libraries/sysinfo.h> or
  153.                      NULL if there was an error
  154.  
  155.   BUGS
  156.  
  157.   SEE ALSO
  158.     RemoveNotify(), <libraries/sysinfo.h>
  159. sysinfo.library/FreeSysinfo                sysinfo.library/FreeSysinfo
  160.  
  161.   NAME
  162.     FreeSysinfo - Finish using the sysinfo.library
  163.  
  164.   SYNOPSIS
  165.     FreeSysinfo(sysinfo);
  166.                 A0
  167.  
  168.     void FreeSysinfo(struct sysinfo *);
  169.  
  170.   FUNCTION
  171.     Declares that you are finished using the services provided by
  172.     sysinfo.library. The sysinfo structure will be freed.
  173.  
  174.   INPUTS
  175.     sysinfo - structure returned by InitSysinfo()
  176.  
  177.   RESULT
  178.     None
  179.  
  180.   BUGS
  181.  
  182.   SEE ALSO
  183.     InitSysinfo(), <libraries/sysinfo.h>
  184. sysinfo.library/GetCpuUsage                sysinfo.library/GetCpuUsage
  185.  
  186.   NAME
  187.     GetCpuUsage - Get the current CPU usage values
  188.  
  189.   SYNOPSIS
  190.     GetCpuUsage(sysinfo, cpu_usage);
  191.                 A0       A1
  192.  
  193.     void GetCpuUsage(struct sysinfo *, struct cpu_usage *);
  194.  
  195.   FUNCTION
  196.     The cpu_usage structure will be filled with current CPU usage
  197.     values.
  198.  
  199.     The sysinfo->cpu_usage_implemented field indicates what values
  200.     are implemented in the sysinfo.library. The corresponding
  201.     bits are defined in <libraries/sysinfo.h>:
  202.  
  203.     CPU_USAGEF_TOTAL_IMPLEMENTED
  204.  
  205.       Total CPU usage. The cpu_usage->total_used_cputime is the CPU time
  206.       used in seconds. The cpu_usage->total_elapsed_time is the used
  207.       cputime plus idle CPU time, i.e. the elapsed time since CPU time
  208.       calculations began. You can calculate the CPU usage percentage
  209.       in this way:
  210.  
  211.           100 * total_used_cputime / total_elapsed_time
  212.  
  213.     CPU_USAGEF_LASTSEC_IMPLEMENTED
  214.  
  215.       CPU time used by all processes during last second. The
  216.       cpu_usage->used_cputime_lastsec_hz is the number of clock
  217.       ticks during one second. The cpu_usage->used_cputime_lastsec
  218.       is the number of ticks used. To calculate the percentage
  219.       of CPU time used:
  220.  
  221.           100 * used_cputime_lastsec / used_cputime_lastsec_hz
  222.  
  223.     CPU_USAGEF_RECENT_IMPLEMENTED
  224.  
  225.       The cpu_usage->recent_used_cputime is a decaying average of
  226.       recent CPU usage. In Executive this is for the last minute.
  227.       The time in seconds is stored in cpu_usage->recent_seconds.
  228.       You can calculate recent CPU usage percentage in this way:
  229.  
  230.          100 * recent_used_cputime / recent_used_cputime_hz
  231.  
  232.     CPU_USAGEF_IVVOCSW_IMPLEMENTED
  233.  
  234.       Some servers can also keep a count of the number of context
  235.       switches. A context switch happens when one task is switched
  236.       to another. The cpu_usage->involuntary_csw field indicates the
  237.       total number of involuntary context switches and the
  238.       cpu_usage->voluntary_csw field indicates the total number of
  239.       voluntary context switches.
  240.  
  241.       Involuntary context switch happens when the CPU is taken
  242.       away from a task that has not finished using it. This happens
  243.       when a higher priority task becomes ready to run.
  244.  
  245.       Voluntary context switch happens when task calls Wait() and
  246.       a lower priority task gets CPU time.
  247.  
  248.     CPU_USAGEF_TOTALCSW_IMPLEMENTED
  249.  
  250.       In some implementations only the total number of context switches
  251.       is available. The cpu_usage->total_csw is just involuntary context
  252.       switches plus voluntary context switches, if specific information
  253.       is available.
  254.  
  255.     CPU_USAGEF_IVVOCSW_LASTSEC_IMPLEMENTED
  256.     CPU_USAGEF_TOTALCSW_LASTSEC_IMPLEMENTED
  257.  
  258.       Like above, but for the last second.
  259.  
  260.     When using these numbers, do all calculations in 32-bits.
  261.  
  262.   INPUTS
  263.     sysinfo - structure returned by InitSysinfo()
  264.     cpu_usage - structure defined in <libraries/sysinfo.h>
  265.  
  266.   RESULT
  267.     None
  268.  
  269.   BUGS
  270.  
  271.   SEE ALSO
  272.     GetTaskCpuUsage(), <libraries/sysinfo.h>
  273. sysinfo.library/GetLoadAverage             sysinfo.library/GetLoadAverage
  274.  
  275.   NAME
  276.     GetLoadAverage - Get load averages
  277.  
  278.   SYNOPSIS
  279.     GetLoadAverage(sysinfo, loadaverage);
  280.                    A0       A1
  281.  
  282.     void GetLoadAverage(struct sysinfo *, struct loadaverage *);
  283.  
  284.   FUNCTION
  285.     This function fills the loadaverage structure with current load
  286.     average values. There are three values which mean the average
  287.     load for the last few minutes. Usually these are 1, 5 and 15
  288.     minutes, but it may vary. The number of seconds each load average
  289.     means, is stored in sysinfo->loadavg_time[1-3]. The number 0 means
  290.     that the load average for that time is not implemented.
  291.  
  292.     The sysinfo->loadavg_type field indicates the way the load averages
  293.     are stored in the loadaverage structure. This can be LOADAVG_NONE,
  294.     in which case the load averages are not available at all.
  295.     LOADAVG_FIXEDPNT means that the load averages are stored as
  296.     32-bit values that have been multiplied with sysinfo->fscale.
  297.     To get the actual load average, you need to calculate in floating
  298.     point numbers:
  299.  
  300.       (float) loadaverage->loadaverage.lavg_fixed.load1 / (float) sysinfo->fscale
  301.  
  302.     If the loadavg_type is LOADAVG_FLOAT, then the load average values
  303.     are in floating point numbers, for example:
  304.  
  305.       loadaverage->loadaverage.lavg_float.load1
  306.  
  307.   INPUTS
  308.     sysinfo - structure returned by InitSysinfo()
  309.     loadaverage - structure defined in <libraries/sysinfo.h>
  310.  
  311.   RESULT
  312.     None
  313.  
  314.   BUGS
  315.  
  316.   SEE ALSO
  317.     <libraries/sysinfo.h>
  318. sysinfo.library/GetNice                    sysinfo.library/GetNice
  319.  
  320.   NAME
  321.     GetNice - get internal priority, nice-value
  322.  
  323.   SYNOPSIS
  324.     nice = GetNice(sysinfo, which, who)
  325.     D0             A0       D0     D1
  326.  
  327.     int GetNice(struct sysinfo *, int, int);
  328.  
  329.   FUNCTION
  330.     Get a nice-value for a process or group of processes. Nice-value
  331.     is used when the server also contains a scheduler, like Executive.
  332.     Nice-value is used when calculating scheduling priorities for tasks.
  333.  
  334.     The nice-value that gives most CPU time is available from
  335.     sysinfo->nicemin (usually -20) and the nice-value that gives
  336.     least CPU time is in sysinfo->nicemax (usually +20).
  337.  
  338.     Which is one of PRIO_PROCESS, PRIO_PGRP, PRIO USER or PRIO_TASK and
  339.     who is interpreted relative to which (a process identifier for
  340.     PRIO_PROCESS, process group identifier for PRIO_PGRP, user ID
  341.     for PRIO_USER and a task address for PRIO_TASK). A zero value of
  342.     who denotes the current process, process group, user or task. Prio
  343.     is a value in the range sysinfo->nicemin to sysinfo->nicemax.
  344.  
  345.     The GetNice() call returns the highest nice-value (usually lowest
  346.     numerical value) enjoyed by any of the specified processes.
  347.  
  348.     Bits in sysinfo->which_implemented indicate what values you can
  349.     use for which. If this value is 0, then GetNice() and SetNice()
  350.     routines are not available.
  351.  
  352.   INPUTS
  353.     sysinfo - structure returned by InitSysinfo()
  354.     which - get priority from which processes
  355.     who - depends on which-field, 0 means current process, PGRP, user or task
  356.  
  357.   RESULT
  358.     nice - highest nice-value enjoyed by any of the specified processes
  359.            -1 is returned if an error occurs. Since -1 is a legitimate
  360.            value, it is necessary to look at sysinfo->errno value if
  361.            -1 is returned by GetNice(). If errno is zero, no error has
  362.            occurred otherwise it will be one of these:
  363.  
  364.      WHICH_ESRCH   No process was located using the which and who values
  365.                    specified.
  366.  
  367.      WHICH_EINVAL  Which was not one of PRIO_PROCESS, PRIO_PGRP,
  368.                    PRIO_USER or PRIO_TASK, or that value is not supported.
  369.  
  370.   NOTES
  371.     The name of this function should have been GetPriority() like in
  372.     Un*x, but it might have been confused with Exec priorities.
  373.  
  374.   BUGS
  375.  
  376.   SEE ALSO
  377.     <libraries/sysinfo.h>
  378. sysinfo.library/GetPgrp                    sysinfo.library/GetPgrp
  379.  
  380.   NAME
  381.     GetPgrp - Get a process group identifier
  382.  
  383.   SYNOPSIS
  384.     pgrp = GetPgrp(sysinfo);
  385.     D0             A0      
  386.  
  387.     int GetPgrp(struct sysinfo *);
  388.  
  389.   FUNCTION
  390.     The process group of the current process is returned by GetPgrp().
  391.  
  392.     If this function is available, the sysinfo->GetPgrp_implemented field
  393.     is TRUE.
  394.  
  395.   INPUTS
  396.     sysinfo - structure returned by InitSysinfo()
  397.  
  398.   RESULT
  399.     pgrp - process group identifier or -1 if process group is unknown
  400.  
  401.   BUGS
  402.  
  403.   SEE ALSO
  404.     GetPid(), GetPpid(), <libraries/sysinfo.h>
  405. sysinfo.library/GetPid                     sysinfo.library/GetPid
  406.  
  407.   NAME
  408.     GetPid - Get a process identifier
  409.  
  410.   SYNOPSIS
  411.     pid = GetPid(sysinfo);
  412.     D0           A0      
  413.  
  414.     int GetPid(struct sysinfo *);
  415.  
  416.   FUNCTION
  417.     GetPid() returns the process ID of the calling task.  The ID is
  418.     guaranteed to be unique and is useful for constructing temporary
  419.     file names.
  420.  
  421.     This routine is always available. If special unique PIDs can't
  422.     be given, it return the task address, so calling this is equivalent
  423.     to calling FindTask(NULL).
  424.  
  425.   INPUTS
  426.     sysinfo - structure returned by InitSysinfo()
  427.  
  428.   RESULT
  429.     pid - process identifier
  430.  
  431.   BUGS
  432.  
  433.   SEE ALSO
  434.     GetPgrp(), GetPpid(), <libraries/sysinfo.h>
  435. sysinfo.library/GetPpid                    sysinfo.library/GetPpid
  436.  
  437.   NAME
  438.     GetPpid - Get a parent process identifier
  439.  
  440.   SYNOPSIS
  441.     pid = GetPpid(sysinfo);
  442.     D0            A0      
  443.  
  444.     int GetPpid(struct sysinfo *);
  445.  
  446.   FUNCTION
  447.     GetPpid() returns the process ID of the parent of the calling task.
  448.  
  449.     If this function is available, the sysinfo->GetPpid_implemented field
  450.     is TRUE.
  451.  
  452.   INPUTS
  453.     sysinfo - structure returned by InitSysinfo()
  454.  
  455.   RESULT
  456.     pid - parent process identifier or -1 if parent is unknown
  457.  
  458.   BUGS
  459.  
  460.   SEE ALSO
  461.     GetPgrp(), GetPid(), <libraries/sysinfo.h>
  462. sysinfo.library/GetTaskCpuUsage            sysinfo.library/GetTaskCpuUsage
  463.  
  464.   NAME
  465.     GetCpuUsage - Get the current CPU usage values for a task
  466.  
  467.   SYNOPSIS
  468.     success = GetTaskCpuUsage(sysinfo, task_cpu_usage, task);
  469.     D0                        A0       A1              A2
  470.  
  471.     int GetTaskCpuUsage(struct sysinfo *, struct task_cpu_usage *, struct Task *);
  472.  
  473.   FUNCTION
  474.     The cpu_usage structure will be filled with current CPU usage
  475.     values for the specified task. Specify NULL for current task.
  476.     This routine is rather similar to GetCpuUsage, but has some
  477.     small differences.
  478.  
  479.     The sysinfo->task_cpu_usage_implemented field indicates what
  480.     values are implemented in the sysinfo.library. The corresponding
  481.     bits are defined in <libraries/sysinfo.h>:
  482.  
  483.     TASK_CPU_USAGEF_TOTAL_IMPLEMENTED
  484.  
  485.       Total CPU usage. The task_cpu_usage->total_used_time_hz is the
  486.       number of clock ticks during one second. The task_cpu_usage->
  487.       total_used_cputime is the total number of ticks used. You can
  488.       calculate the CPU usage percentage in this way:
  489.  
  490.           100 * total_used_cputime / total_used_time_hz
  491.  
  492.       The task_cpu_usage->total_elapsed_time is the used CPU time plus
  493.       idle CPU time, i.e. the elapsed time since the task was created.
  494.       You can calculate how many percent of CPU time task has used:
  495.  
  496.           100 * (total_used_cputime / total_used_time_hz) / total_elapsed_time
  497.  
  498.       Please remember that this number doesn't mean the percentage
  499.       of CPU time the task has used from all used CPU time. It's
  500.       the percentage of CPU time the task has used from the total
  501.       available CPU time.
  502.  
  503.     TASK_CPU_USAGEF_LASTSEC_IMPLEMENTED
  504.  
  505.       CPU time used by this task during last second. The
  506.       cpu_usage->used_cputime_lastsec_hz is the number of clock
  507.       ticks during one second. The cpu_usage->used_cputime_lastsec
  508.       is the number of ticks used. To calculate the percentage
  509.       of CPU time used:
  510.  
  511.           100 * used_cputime_lastsec / used_cputime_lastsec_hz
  512.  
  513.     TASK_CPU_USAGEF_RECENT_IMPLEMENTED
  514.  
  515.       The cpu_usage->recent_used_cputime is a decaying average of
  516.       recent CPU usage. In Executive this is for the last minute.
  517.       The time in seconds is stored in cpu_usage->recent_seconds.
  518.       You can calculate recent CPU usage percentage in this way:
  519.  
  520.          100 * recent_used_cputime / recent_used_cputime_hz
  521.  
  522.     TASK_CPU_USAGEF_IVVOCSW_IMPLEMENTED
  523.  
  524.       Some servers can also keep a count of the number of context
  525.       switches. A context switch happens when one task is switched
  526.       to another. The cpu_usage->involuntary_csw field indicates the
  527.       total number of involuntary context switches for the specified
  528.       task and the cpu_usage->voluntary_csw field indicates the total
  529.       numnber of voluntary context switches.
  530.  
  531.       Involuntary context switch happens when the CPU is taken
  532.       away from a task that has not finished using it. This happens
  533.       when a higher priority task becomes ready to run.
  534.  
  535.       Voluntary context switch happens when task calls Wait() and
  536.       a lower priority task gets CPU time.
  537.  
  538.     TASK_CPU_USAGEF_TOTALCSW_IMPLEMENTED
  539.  
  540.       In some implementations only the total number of context switches
  541.       is available. The cpu_usage->total_csw is just involuntary context
  542.       switches plus voluntary context switches, if specific information
  543.       is available.
  544.  
  545.     TASK_CPU_USAGEF_IVVOCSW_LASTSEC_IMPLEMENTED
  546.     TASK_CPU_USAGEF_TOTALCSW_LASTSEC_IMPLEMENTED
  547.  
  548.       Like above, but for the last second.
  549.  
  550.     When using these numbers, do all calculations in 32-bits.
  551.  
  552.   INPUTS
  553.     sysinfo - structure returned by InitSysinfo()
  554.     cpu_usage - structure defined in <libraries/sysinfo.h>
  555.     task - task address, NULL for current task
  556.  
  557.   RESULT
  558.     success - 0 for success, 1 for error
  559.  
  560.   BUGS
  561.  
  562.   SEE ALSO
  563.     GetCpuUsage(), <libraries/sysinfo.h>
  564. sysinfo.library/InitSysinfo                sysinfo.library/InitSysinfo
  565.  
  566.   NAME
  567.     InitSysinfo - Initialize the sysinfo.library
  568.  
  569.   SYNOPSIS
  570.     sysinfo InitSysinfo(void);
  571.     D0
  572.  
  573.     struct sysinfo *InitSysinfo(void);
  574.  
  575.   FUNCTION
  576.     This function will initialize the sysinfo.library and possibly
  577.     make a connection to the server task. It returns a sysinfo structure
  578.     which you need when requesting information. The structure is read-
  579.     only and it's size may grow in later versions of the library.
  580.  
  581.   INPUTS
  582.     None
  583.  
  584.   RESULT
  585.     sysinfo - structure defined in <libraries/sysinfo.h>
  586.  
  587.   BUGS
  588.  
  589.   SEE ALSO
  590.     FreeSysinfo(), <libraries/sysinfo.h>
  591. sysinfo.library/RemoveNotify               sysinfo.library/RemoveNotify
  592.  
  593.   NAME
  594.     RemoveNotify - Remove a notification request
  595.  
  596.   SYNOPSIS
  597.     RemoveNotify(sysinfo,sysinfo_notify);
  598.                  A0      A0
  599.  
  600.     void RemoveNotify(struct sysinfo *, struct sysinfo_notify);
  601.  
  602.   FUNCTION
  603.     Remove the notification request added with AddNotify(). This function
  604.     will internally make sure that you won't get any more notification
  605.     messages and it will clean up the queued messages if any. It will
  606.     also clear the signal if it was allocated.
  607.  
  608.   INPUTS
  609.     sysinfo - sysinfo structure returned by InitSysinfo()
  610.     sysinfo_notify - the sysinfo_notify structure you got from AddNotify()
  611.  
  612.   RESULT
  613.     None
  614.  
  615.   BUGS
  616.  
  617.   SEE ALSO
  618.     AddNotify(), <libraries/sysinfo.h>
  619. sysinfo.library/SetNice                    sysinfo.library/SetNice
  620.  
  621.   NAME
  622.     SetNice - set internal priority, nice-value
  623.  
  624.   SYNOPSIS
  625.     success = SetNice(sysinfo, which, who, nice)
  626.     D0                A0       D0     D1   D2
  627.  
  628.     int SetNice(struct sysinfo *, int, int, int);
  629.  
  630.   FUNCTION
  631.     Set a nice-value for a process or group of processes. 
  632.  
  633.     See GetNice() for more information.
  634.  
  635.   INPUTS
  636.     sysinfo - structure returned by InitSysinfo()
  637.     which - which processes are affected
  638.     who - depends on which-field, 0 means current process, PGRP, user or task
  639.     nice - change nice to this value
  640.  
  641.   RESULT
  642.     success - 0 if there is no error, or -1 if there is, in which case
  643.               the error is in sysinfo->errno:
  644.  
  645.      WHICH_ESRCH   No process was located using the which and who values
  646.                    specified.
  647.  
  648.      WHICH_EINVAL  Which was not one of PRIO_PROCESS, PRIO_PGRP,
  649.                    PRIO_USER or PRIO_TASK, or that value is not supported.
  650.  
  651.      Some implementations may returns one of these:
  652.  
  653.      WHICH_EPERM   A process was located, but neither its effective nor real
  654.                    user ID matched the effective user ID of the caller.
  655.  
  656.      WHICH_EACCES  A non super-user attempted to lower a process priority.
  657.  
  658.   NOTES
  659.     The name of this function should have been SetPriority() like in
  660.     Un*x, but it might have been confused with Exec priorities.
  661.  
  662.   BUGS
  663.  
  664.   SEE ALSO
  665.     <libraries/sysinfo.h>
  666.